Skip to content

docs: publish the 2026-07-29 review, the ADR log, and retire ISSUES.md - #150

Merged
Xof merged 4 commits into
mainfrom
docs/publish-review-adr-and-retire-issues
Aug 5, 2026
Merged

docs: publish the 2026-07-29 review, the ADR log, and retire ISSUES.md#150
Xof merged 4 commits into
mainfrom
docs/publish-review-adr-and-retire-issues

Conversation

@Xof

@Xof Xof commented Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Stacked on #149.

Brings three pieces of project documentation onto the published lineage. No code changes — 712 tests still pass.

What lands

  1. docs/reviews/review-20260729-183138.md — the clean-slate deep review that every issue in the Trust-boundary hardening gaps found by the cross-cutting security sweep #102Cleanups in the cross-subsystem gaps #126 range cites. Those issue bodies link to this file; until now the link 404'd on this lineage.
  2. docs/adr/00000017 — the decision log as per-decision files plus a generated README.md index. Previously the ADRs existed only on the orphaned dev lineage.
  3. ISSUES.md retirement — the 1868-line tracked issue log is deleted, its open entries having been migrated to GitHub issues (I78: Per-insert full-page XXH3 re-stamp on the slot-packing path #138I160: RadixU64::insert(u64::MAX) infinite grow loop + delete lacks find_leaf's cap guard (latent) #148). ADR 0017 records the decision.

On the I<number> markers

~167 code comments cite issue ids like I61 (ISSUES.md, 2026-05-22). These were deliberately not rewritten: most refer to entries closed long ago with no GitHub equivalent, so a rewrite would delete provenance across 167 sites for no navigational gain. ARCHITECTURE.md gains a note explaining how to read them, and the file remains readable at git show 0ffe3bc:ISSUES.md.

Review findings addressed

A docs review (Sonnet 5) checked dangling references, link integrity, ADR frontmatter validity, supersession symmetry, and factual claims. It confirmed all 18 ADR links resolve, ids are unique and match filenames, ADR 0017's issue-mapping claims are correct against live GitHub, and git show 0ffe3bc:ISSUES.md resolves. Two findings were real and are fixed in the final commit:

  • Six ADR records cite ISSUES.md as live. Their bodies are Accepted and are superseded rather than edited, so the citations stay — but record 0000 (the register overview, not a decision) claimed smaller decisions "live in ISSUES.md", which the deleting commit makes false. 0000 now carries the resolution breadcrumb for the whole log, and 0017 records the dead-citation gap as an explicit consequence of its own decision.
  • The review record misstated a commit distance — "five commits ago" for the I143 regression, where git rev-list --count 04534c0..d87e670 is 2.

adr_index.py exits 0 (18 records) and regenerates README.md identically, confirming the index was generated rather than hand-edited.

Xof added 4 commits August 4, 2026 13:51
Thirteen reviewers over disjoint slices of the workspace, forbidden from
reading ISSUES.md and docs/reviews/ so the pass would be genuinely
clean-slate, then an adversarial verification pass instructed to refute.
140 findings: 5 BUG, 64 DESIGN, 57 SMELL, 14 NIT.

The document records its own reliability caveat, which is the reason to keep
it: a 1-in-137 refutation rate is the rubber-stamping failure mode, so the
five BUG-severity findings were re-verified by hand from the source rather
than taken on a verifier's word.

Every other review in docs/reviews/ is tracked; this one was left untracked
when its findings were filed as issues #102-#126.
The 17 architecture decision records existed only on design/swift-binding,
which descends from the pre-release development lineage. That lineage shares
no history with origin/main, so nothing on it can reach the published
repository through a pull request, and the decision log has been invisible
from every branch that can.

Copied verbatim, no edits: these are Accepted records and their bodies are
frozen. A path checkout is used rather than a merge precisely because the two
lineages have no common ancestor.

The Swift binding itself remains stranded on that branch and still needs a
route onto this lineage.
ISSUES.md had grown to 1868 lines across 119 numbered entries and could no
longer be read whole by a session that also needed to hold the code — the
2026-07-29 review deliberately withheld it from its reviewers for that reason,
which is an admission that the log had stopped being usable as an input. It
also duplicated a tracker the project already used, under a second set of
identifiers, and its statuses drifted: I149 and I150 were both still marked
OPEN although I150 shipped in PR #128 and I149 shipped two commits ago.

Of the 14 open and 3 deferred entries, 6 were already represented in existing
issues (I147 in #116, I149 and I150 in #102, I151 in #107, I152 and I154 in
#106). The remaining 11 were filed as #138-#148, each carrying its entry
verbatim plus a header naming its original id and source review. I78 needed
its header line preserved as well, because it recorded a correction that
contradicts the caveat in its own body.

The 83 entries marked fixed were not migrated. They describe completed work
and remain in git history at 0ffe3bc. This is the real cost of the change and
ADR 0017 records it as such: those entries are no longer discoverable by grep
in a checkout, and some of them hold genuine decision rationale.

The ~167 I<number> markers in source comments are deliberately left alone.
Most refer to entries closed long ago with no GitHub equivalent, so rewriting
them would delete provenance across 167 sites for no navigational gain.
ARCHITECTURE.md gains a note explaining what they mean and how to retrieve
the retired file; the live links in README.md, ARCHITECTURE.md and THEORY.md
now point at docs/adr/ and the issue tracker instead.
Two things the docs review caught.

The ADR log was ported from the retired lineage with its `ISSUES.md`
citations intact, which is correct — an Accepted record is superseded, not
edited — but README.md and ARCHITECTURE.md now route readers to `docs/adr/`
as *the* decision log, so a reader following that pointer lands on citations
with no way to resolve them. Record 0000 is the register overview rather than
a decision, so it carries the breadcrumb for the whole log; 0017 records the
same gap as an explicit consequence of the retirement it decides. Record
0000's claim that smaller decisions "live in ISSUES.md" was simply false as
of the commit that deletes the file.

The review record put the I143 regression 'five commits' before its own
baseline; `git rev-list --count 04534c0..d87e670` is 2.
@Xof
Xof changed the base branch from fix/102-trust-boundary-hardening to main August 5, 2026 03:41
@Xof
Xof merged commit 1506cd7 into main Aug 5, 2026
@Xof
Xof deleted the docs/publish-review-adr-and-retire-issues branch August 5, 2026 03:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant